Skip to content

feat: Add Renderers for Yields #402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: Add Renderers for Yields #402

wants to merge 2 commits into from

Conversation

Lawrence-Godfrey
Copy link

Should solve #338

quartodoc version: 0.11.1

Problem

Currently if I have a Yields: section in a function, e.g.,

@asynccontextmanager
async def get_session_factory(
    session_factory_instance: async_sessionmaker[AsyncSession],
) -> AsyncGenerator[AsyncSession, None]:
    """
    Yields an AsyncSession

    Args:
        session_factory_instance: An async sessionmaker instance to 'yield' sessions from and close them asynchronously.

    Yields:
        An AsyncSession instance.
    """
    async with session_factory_instance() as session:
        try:
            yield session
        finally:
            await session.close()

I get the following error:

  File "/home/.../Documents/.../.venv/lib/python3.10/site-packages/quartodoc/renderers/md_renderer.py", line 309, in render
    raise NotImplementedError(f"Unsupported type: {type(el)}")
NotImplementedError: Unsupported type: <class '_griffe.docstrings.models.DocstringSectionYields'>

Solution

Adding renderers in md_renderer.py for DocstringSectionYields and DocstringSectionYields (basically exactly the same renders for Returns) everything renders nicely.

image

Seems to work with parser: numpy too.
Also seems to handle interlinks correctly as far as I can tell.

@Lawrence-Godfrey Lawrence-Godfrey changed the title Add Renderers for the Yields Add Renderers for Yields Jul 4, 2025
@Lawrence-Godfrey Lawrence-Godfrey changed the title Add Renderers for Yields feat: Add Renderers for Yields Jul 5, 2025
@codecov-commenter
Copy link

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 60.00000% with 4 lines in your changes missing coverage. Please review.

Project coverage is 88.75%. Comparing base (e28324d) to head (d53796e).

Files with missing lines Patch % Lines
quartodoc/renderers/md_renderer.py 60.00% 4 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main     #402      +/-   ##
==========================================
- Coverage   88.86%   88.75%   -0.11%     
==========================================
  Files          40       40              
  Lines        3027     3033       +6     
==========================================
+ Hits         2690     2692       +2     
- Misses        337      341       +4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@machow
Copy link
Owner

machow commented Jul 14, 2025

Thanks so much for adding this! I'm dumping the numpydoc yields spec below, just so I can quickly reference:

image

@machow
Copy link
Owner

machow commented Jul 14, 2025 •
edited
Loading

This seems pretty straightforward, and should be quick to merge! Would you mind adding a simple test? I think it'd be okay to just duplicate this returns test for now.

(I'm always happy to swing in and add the test if useful :)

edit: I think the CI for doc build will always fail, since it's an external PR. I can fix separate from this PR 😓.

@Lawrence-Godfrey
Copy link
Author

This seems pretty straightforward, and should be quick to merge! Would you mind adding a simple test? I think it'd be okay to just duplicate this returns test for now.

(I'm always happy to swing in and add the test if useful :)

edit: I think the CI for doc build will always fail, since it's an external PR. I can fix separate from this PR 😓.

Have added testcases for Numpy and Google style docstrings with Yields in them.

@SalmanMohammadi
Copy link

Hi @machow @Lawrence-Godfrey - is this still planned? We're also running into this issue and the fix would be great to have.

@SalmanMohammadi SalmanMohammadi mentioned this pull request Aug 13, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@Lawrence-Godfrey @codecov-commenter @machow @SalmanMohammadi